Stub Status

stub_status is a built-in NGINX module that exposes real-time internal metrics about how NGINX is handling connections and requests.

It is mainly used for:

• Health monitoring
• Traffic analysis
• Capacity planning
• Detecting DoS / traffic spikes
• Feeding monitoring systems (Prometheus, Zabbix, Datadog, etc.)

It does not log data — it exposes live status metrics.

What stub_status Is Not

Not a replacement for	Reason
Access logs	No per-request data
Error logs	No error details
APM tools	No application metrics

It answers “how busy is NGINX right now?”

How stub_status Works Internally

• NGINX maintains internal counters for:
  • Connections
  • Requests
• When /nginx_status is accessed:
  • NGINX prints current counter values
• Metrics reset only when:
  • NGINX restarts

Extremely lightweight, Near-zero performance impact

Enabling stub_status

Check if Module Is Available

nginx -V 2>&1 | grep stub_status

Most distributions include it by default.

Basic Configuration

server {
    listen 127.0.0.1:8080;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Example Output of stub_status

Accessing: curl http://127.0.0.1:8080/nginx_status

Output:

Active connections: 291
server accepts handled requests
 10234567 10234567 20456789
Reading: 2 Writing: 5 Waiting: 284

Understanding Each Metric (Very Important)

Active Connections

Active connections: 291

Total current open connections, including:

• Reading
• Writing
• Waiting (keep-alive)

Accepts / Handled / Requests

server accepts handled requests
 10234567 10234567 20456789

Not a replacement for	Reason
Access logs	No per-request data
Error logs	No error details
APM tools	No application metrics

requests can be higher than handled (keep-alive).

Reading / Writing / Waiting

Reading: 2 Writing: 5 Waiting: 284

Metric	Meaning
accepts	TCP connections accepted
handled	Connections successfully handled
requests	Total HTTP requests served

High Waiting is normal on busy sites.

Monitoring Use Cases

Detecting Traffic Spikes / DDoS

Symptom	Interpretation
Sudden spike in Active connections	Possible flood
High Reading	Slowloris attack
High Writing	Backend slow
Growing Waiting	Too many keep-alive clients

Capacity Planning

• Compare:
  • Active connections
  • worker_connections
• Helps decide when to scale

Securing stub_status (Very Important)

Never expose publicly, Restrict access

location /nginx_status {
   stub_status;
   allow 127.0.0.1;
   allow 10.0.0.0/8;
   deny all;
}

• Prevents information leakage
• Blocks attackers from learning capacity

Using stub_status with Monitoring Systems

Example: Prometheus (via exporter)

• NGINX → /nginx_status
• Exporter scrapes metrics
• Prometheus stores data
• Grafana visualizes

stub_status is the foundation for most NGINX monitoring stacks.

Container / Kubernetes Setup

location /nginx_status {
    stub_status;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

• Disable access logs (no noise)
• Scraped internally

Common Mistakes

Symptom	Interpretation
Sudden spike in Active connections	Possible flood
High Reading	Slowloris attack
High Writing	Backend slow
Growing Waiting	Too many keep-alive clients

Comparing stub_status vs NGINX Plus

Symptom	Interpretation
Sudden spike in Active connections	Possible flood
High Reading	Slowloris attack
High Writing	Backend slow
Growing Waiting	Too many keep-alive clients

Recommended Production Configuration

    server {
    listen 127.0.0.1:8080;

        location /nginx_status {
            stub_status;
            access_log off;

            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

    }